Chapitre 5 [coord] Les outils de travail

La démarche PROPRE nécessite des moyens de communication au sein et entre les équipes. Les outils sont aussi les outils de développement puisque l’objectif est de produire un rapport d’analyse reproductible. Il convient de veiller à ce que le nombre d’outils différents soit limité pour favoriser l’entrée de nouveaux participants dans le processus. Dans cette section, nous proposons des outils accessibles à tous, qui ne limitent pas les développeurs et qui permettent d’intégrer des éditeurs, quelque soit leurs connaissances informatiques préalables. Bien sûr, il pourra être judicieux de prévoir une formation pour homogénéiser les pratiques et les utilisations. Le présent livre numérique étant un support de cet accompagnement.

5.1 Outils et moyens de communiquer

La coordination se passe mieux lorsque chacun a les outils pour communiquer, échanger, à tous les niveaux du projet. Sur un projet de développement informatique, il est judicieux d’utiliser des outils de gestion de projet qui font le lien direct avec le code. Pour le projet {propre.rpls}, nous avons notamment décidé de travailler avec GitLab.
Nous privilégions aussi autant que possible les logiciels libres et open-source (même si des alternatives propriétaires sont listées ici). Les différents outils numériques auxquels penser sont les suivants :

• Communication asynchrone par chat : Rocket Chat, Slack, …
  • Créer une chaîne globale pour discuter du projet en général, une chaîne dédiée à la communication entre [Dev] et une chaîne dédiée à la communication entre membres du comité éditorial [Ed].Vous pouvez aussi créer une chaîne pour votre dépôt GitLab ou GitHub, ce qui permet de centraliser dans le Chat les informations venant de celui-ci (création de ticket, …).
• Communication synchrone en visioconférence : Jitsi, Zoom, Microsoft Teams, …
• Communication technique asynchrone sur forum de discussion approprié : Tickets GitLab, issues Github, …
  • Créer un projet GitLab dès le début du projet et y inviter tous les membres du projet, développeurs comme éditeurs.
• Stockage des fichiers (backlog, comptes-rendus) : Etherpad, GitLab, Nextcloud
  • Le projet {propre.rpls} utilise un pad collaboratif auto-hébergé pour prendre les notes lors des réunions avec l’outil open-source etherpad notamment.
  • Le projet {propre.rpls} utilise le Wiki du projet GitLab pour stocker les documents à l’issue des discussions.

5.2 Outils de développement et d’édition

Un processus reproductible passe généralement par des outils de programmation. Le code développé doit être documenté de telle sorte que n’importe quel développeur, inclu dans le processus depuis le début ou non, puisse reprendre le code créé par ses collaborateurs.
Ce code doit aussi être versionné pour qu’il soit possible de revenir dans le temps en cas de problème, pour qu’on puisse s’adresser à la bonne personne pour demander des explications de code.

Pour le projet {propre.rpls}, nous avons choisi de travailler avec le langage de programmation R. Le développement se réalise dans des documents “RMarkdown” (ou “Notebook”) auto-suffisants, mélangeant textes d’explication et code complet de façon à ce que n’importe qui puisse comprendre et reproduire les étapes présentées. Notons que l’équipe éditoriale est aussi formée à rédiger ses contenus en utilisant les mêmes outils que l’équipe de développement. Nous avons aussi choisi de développer dans un format “package”, ce qui, dans le langage R, contraint les développeurs à fournir un code testé par une procédure de validation automatique.

Les contraintes techniques et les outils nécessaires au développement et à l’édition dans le cadre de PROPRE sont :

• Le versionnement du code et des textes pour le suivi des modifications dans le temps : git
  • Notons que le Wiki GitLab est versionné.
• La centralisation des modifications de tous les développeurs et éditeurs sur un serveur distant : GitLab, Github, …
• La mise en place d’une procédure automatique de test du code localement et sur le serveur distant : “Check” d’un package R, Intégration Continue
  • Le projet {propre.rpls} utilise l’intégration continue (CI) de GitLab pour la validation automatique des propositions de modifications
• Mise en ligne de la publication et de ses dérivées pour validation: GitLab pages, Github pages, …
  • Le projet {propre.rpls} utilise l’intégration continue de GitLab et les “GitLab Pages” pour construire, automatiquement pour chaque modification, un site web dédié au projet avec toutes les productions
• Un IDE commun de développement et d’édition : Rstudio, VSCode, …
  • Notons qu’une mutualisation de l’outil de développement, notamment sur un serveur commun, permet de réduire les risques de versions de logiciels différents que ce soit chez les développeurs ou chez les éditeurs

5.3 Utiliser le format Markdown pour prendre les notes

Le format de rédaction des différents documents de développement et d’échanges sera le markdown. Il est recommandé d’utiliser ce format d’écriture pour la totalité des textes rédigés lors du projet, y compris pour les comptes-rendus de réunion. D’où l’utilisation du pad collaboratif comme indiqué plus haut.

Avec le Markdown, nous séparons le fond de la forme. Ici, peu importe la façon dont les informations apparaissent. Nul besoin de rouge, de souligné, de paillettes… Jolie ou non, l’important c’est que l’information soit présente et correctement structurée. En utilisant le format d’écriture Markdown, les rédacteurs ([Red]) se familiarisent avec les outils des [Dev] tout en réduisant leur charge mentale en utilisant un langage avec peu de formatage à apprendre (cf. page wikipédia sur le markdown). Quoi qu’il arrive, les rédacteurs devront utiliser ce format au cours du projet puisque c’est le format utilisé dans la création des publications reproductibles. Alors autant s’y mettre au plus vite lorsqu’il n’y a pas de stress.

Le texte s’écrit dans un fichier texte à ouvrir avec notepad par exemple et à enregistrer avec l’extension md : mes_besoins.md. Écrivez votre texte comme si vous étiez dans votre éditeur de texte préféré, mais utilisez le formatage suivant :

• # Un dièse pour un titre de niveau 1
• ## Deux dièses pour un titre de niveau 2
• ### Trois dièses pour un titre de niveau 3
• - Une ligne vide, puis une ligne qui commence par le signe moins “-” pour une liste comme celle que vous lisez actuellement
  
• **Entourer son texte avec deux doubles étoiles pour qu'il apparaisse en gras**
• _Entourer son texte avec deux underscores ("tiret du 8") pour qu'il apparaisse en italique_
• [Afficher un lien vers internet avec des crochets pour le texte et des parenthèses pour l'url](https://url-ici.com)

Les [Dev] se feront ensuite un plaisir de montrer qu’ils peuvent transformer sans effort ce format Markdown en HTML, PDF et même en Word…

Le document que vous lisez actuellement a d’ailleurs été entièrement rédigé avec cette syntaxe, ce qui permet de le produire aussi bien en HTML qu’en PDF. Le formatage de son apparence finale est à la charge d’autres développeurs. Il est disponible et donc reproductible pour n’importe quel autre projet. Oui, en quelque sorte, nous utilisons la méthode PROPRE pour rédiger les documents sur la méthode PROPRE…